Coupon Stash v1.4 - User Guide

image

By: Team F09-1

Contents Section Number

Introduction

1

About This Document

2

Quick Start

3

Features

  1. Adding a coupon: add

  2. Editing a coupon: edit

  3. Deleting a coupon: delete

  4. Listing all coupons: list

  5. Using a coupon: used

  6. Viewing savings: saved

  7. Archiving a coupon: archive

  8. Unarchiving a coupon: unarchive

  9. Locating coupons by name: find

  10. Listing all expiring coupons: expiring

  11. Sorting coupons: sort

  12. Copying a coupon: copy

  13. Sharing a coupon: share

  14. Undoing the previous command: undo

  15. Redoing the undone command: redo

  16. Displaying a month-year on the calendar: goto

  17. Displaying a coupon: expand

  18. Setting currency symbol: setcurrency

  19. Viewing help: help

  20. Clearing all entries: clear

  21. Exiting the program: exit

  22. Reminding of coupon expiry

  23. Saving the data

4

Keyboard Shortcuts

  1. Restore previously entered command texts: ↑ and ↓

  2. Close expanded coupon window: Ctrl+q

  3. Cycle through tabs: Ctrl+Tab

5

FAQ

6

Command Summary

7

Appendix

8

Welcome to the Coupon Stash User Guide! Thank you so much for choosing Coupon Stash, the world’s most popular command-line coupon management desktop application*!

This guide will help you get started quickly, providing useful tips and hints along the way.

*as of April 2020

1. Introduction

Coupon Stash is meant for School of Computing (SoC) students and staff who enjoy managing their coupons with a desktop command-line interface. It is optimised for efficient usage in this aspect, while still offering a sleek, beautiful Graphical User Interface (GUI).

Jump to the Quick Start section to get started now. We sincerely hope you enjoy using Coupon Stash!

2. About This Document

This document introduces the features of Coupon Stash.

The following are symbols and formatting used in this document:

Tip
 Tips are used to describe small features or techniques that may come in handy when using Coupon Stash!
Warning
 Warnings bring your attention to certain practices that may have unintended consequences!
Note
 Notes describe certain features or behaviour that may not be so obvious!

Boxes like these contain useful information, for emphasis and easy reference!

  • Coupon Stash command words are formatted with code blocks.

3. Quick Start

  1. Ensure you have Java (version 11 or above) installed in your Computer.

  2. Download the latest CouponStash.jar.

  3. Copy the file to the folder you want to use as the home folder for your Coupon Stash.

  4. Double-click the file to start the app. The GUI should appear in a few seconds. If nothing occurs, use the command java -jar CouponStash.jar on your computer’s Command Line Interface (CLI) to open the file up.

  5. Type the command in the command box and press Enter to execute it.

  6. Some example commands you can try:

    • list : lists all coupons

    • add: add n/Domino’s Pizza Extra Large s/40% p/ILOVEDOMINOS e/30-4-2020 l/5 t/pizza t/delivery

      • adds a coupon named Domino’s Pizza Extra Large to the Coupon Stash, with an expiry date of 30th April 2020, 40% savings with promo code ILOVEDOMINOS, and a limit of 5 usages.

    • delete: delete 3 : deletes the 3rd coupon shown in the current list

    • exit : exits the app (your data will be saved automatically)

  7. Refer to the Features section below for the details of each command.

4. Features

This section introduces the features of Coupon Stash. There are some examples for you to try out in Coupon Stash too!
Also, take note of the general format of all the commands below!

Note

Command Format

  • Words in UPPERCASE: parameters to be supplied by you (the user)

    • e.g. add n/NAME

  • INDEX: positive integer that specifies the index number shown in the displayed coupon list. The index must be a positive integer

    • e.g. 1, 2, 3, …​

  • NAME is a parameter which can be used as add n/The Deck Chicken Rice

  • Letter(s) followed by a / : prefixes to come before some parameters

    • e.g. n/NAME

    • n/ is the prefix for the NAME parameter

  • Items in square brackets: optional

    • e.g n/NAME [t/TAG]

    • Can be used as n/The Deck Chicken Rice t/value or n/The Deck Chicken Rice

  • Items with …​ after them: can be used multiple times (including zero times)

    • e.g. [t/TAG]…​​

    • can be used as t/pizza, t/friend t/value or not used at all etc.

  • Parameters can be in any order

    • e.g. specifying n/NAME s/SAVINGS is the same as s/SAVINGS n/NAME

  • Dates are all in the D-M-YYYY format (Coupon Stash date format)

    • D and M can be one or two digits, but YYYY has to be four digits

    • e.g. 1-1-2020 and 01-01-2020 are valid dates

  • MonthYear are all in the M-YYYY format (Coupon Stash MonthYear format)

    • M can be one or two digits, but YYYY has to be four digits

    • e.g. 1-2020 and 01-2020 are valid MonthYears

4.1. Adding a coupon: add

Adds a coupon. Some fields like name, expiry date and savings are required. Optional fields like promo code and tags may be provided as well.

Format: add n/NAME e/EXPIRY_DATE s/SAVINGS_OR_FREE_ITEM [sd/START_DATE] [r/REMIND_DATE] [p/PROMO_CODE] [c/CONDITIONS] [u/USAGE] [l/USAGE_LIMIT] [s/EXTRA_FREE_ITEMS]…​ [t/TAG]…​

Tip
 A coupon can have any number of tags (including 0)
Note
 If unspecified, the default remind date of a coupon will be set to 3 days before the expiry date. Go to Section 4.22, “Reminding of coupon expiry” to learn more about remind dates.

  • Coupons must have at least one "savings" value, whether it is a flat monetary amount (e.g. $1.00), a percentage (e.g. 10%) or an item. (e.g. Free Water Bottle)

  • Savings can be represented by multiple free items, but not multiple monetary amounts or percentage amounts.

  • Free item names cannot contain any numbers. (e.g. iPhone 11 is an invalid free item name as it contains the number 11)

  • Coupons cannot have both a monetary amount and a percentage amount.

  • To add more free items, use the same prefix as before!

Examples:

  • add n/McDonald’s McGriddles p/ILOVEMCGRIDDLES e/31-12-2020 s/$2 sd/1-4-2020 l/2 t/value t/savoury

    Adds a new Coupon:
    ug mcdonalds mcgriddles

  • add n/Grabfood s/40% e/30-4-2020 p/GRAB40 t/delivery

    Adds a new Coupon:
    ug grabfood

Tip
 If your coupon allows for unlimited usage, set the limit of the coupon to a number less than 1! E.g. l/0

4.2. Editing a coupon: edit

Edits an existing coupon in the coupon book.

Format: edit INDEX [n/NAME] [e/EXPIRY_DATE] [sd/START_DATE] [r/REMIND_DATE] [p/PROMO_CODE] [c/CONDITION] [l/USAGE_LIMIT] [s/SAVINGS_OR_FREE_ITEMS]…​ [t/TAG]…​

  • Edits the coupon at the specified INDEX.

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the coupon will be removed. (i.e adding of tags is not cumulative)

  • You can remove all of a coupon’s tags by typing t/ without specifying any tags after it.

  • When editing savings, just like tags, existing savings of the coupon will also be removed.

  • Usage cannot be edited.

Note
 Savings cannot be cleared in the same way as clearing tags, as a coupon must have at least 1 saving.
Note
 Remind date cannot be removed or cleared. Go to Section 4.22, “Reminding of coupon expiry” to learn more about remind dates.

Examples:

  • edit 1 s/50%
    Edits the savings of the 1st coupon to be 50% off.

  • edit 2 n/The Deck Nasi Ayam Hainan t/
    Edits the name of the 2nd coupon to be The Deck Nasi Ayam Hainan and clears all existing tags.

4.3. Deleting a coupon: delete

Deletes the specified coupon from the coupon stash.

Version 2.0 will bring new features like confirmation of coupons before they are deleted!

Also, a "recycle bin" is in the works for version 3.0, similar to the Recycle Bin in Microsoft Windows.

Format: delete INDEX

  • Deletes the coupon at the specified INDEX.

Examples:

  • list
    delete 2
    Deletes the 2nd coupon in the coupon stash.

  • find rice
    delete 1
    Deletes the 1st coupon in the results of the find command.

4.4. Listing coupons: list

Shows a list of coupons in the coupon stash.

There are 3 types of lists:

  1. List of active coupons

  2. List of archived coupons

  3. List of used coupons

Format: list [PREFIX]

  • The PREFIX can be either a/ or u/.

  • Using a/ lists all coupons that are archived, while u/ lists all coupons that are used before.

Note
 PREFIX can be left blank to list all active coupons. (coupons that are not expired/ not fully used/ not archived)

Examples:

  • list
    Shows a list of all active coupons

  • list a/
    Shows a list of all archived coupons

  • list u/
    Shows a list of all used coupons (but not fully used)

4.5. Using a coupon: used

Uses a coupon if its usage has yet to reached its limit. Requires an original amount of purchase if the coupon has savings in a percentage value.

Format: used INDEX or used INDEX MONETARY_AMOUNT where MONETARY_AMOUNT is a number prefixed by a user-defined currency symbol e.g. ($4.50, where the currency symbol is "$").

  • Uses the coupon at the specified INDEX.

Examples:

  • used 1
    Uses the first coupon in the coupon stash.

  • used 1 $10.0
    Uses the first coupon in the coupon stash, which also has a percentage savings. The total savings of the coupon will be calculated, and can be seen with the command saved.

Warning
 A coupon cannot be used if it has not reached its start date, or it is archived. If there is an intention to use the coupon, you can edit the start date or unarchive the coupon.

4.6. Viewing savings: saved

Shows you how much you have saved by using coupons in Coupon Stash. There are three ways to use this command:

  • If just the word "saved" is entered, the total savings accumulated since you started using Coupon Stash will be shown.

    Format: saved

  • If a specific date is given, Coupon Stash will show you savings earned only on that day.

    Format: saved d/DATE_TO_SHOW

  • If a start date and end date are given, Coupon Stash will show you the total savings accumulated over all the dates between that start date and end date, inclusive of those dates as well.

    Format: saved sd/START_DATE e/END_DATE

  • Dates are given in Coupon Stash date format, namely D-M-YYYY where D and M can be single or double digits.

  • Shows you a numeric value (e.g. 12.00 to represent twelve dollars/euros/pounds/pesos) that represents how much money you saved since a certain date, as well as certain items that you might have saved.

  • This value changes depending on which coupons were marked as used during the time period specified.

Examples:

  • saved d/1-3-2020
    A message will be displayed: You have saved $6.50 as well as earned 2x Brattby Bag on 1 March 2020.

  • saved sd/1-5-2019 e/20-3-2020
    A message will be displayed: You have saved $117.15 as well as earned 5x Brattby Bag, 7x Water Bottle, 12x Free Coffee, 1x Plush Toy between 1 May 2019 and 20 March 2020.

4.7. Archiving a coupon: archive

Archives a coupon when you want to keep a record of it, without cluttering your current stash of coupons.

Note
 To view archived coupons, the user can run the list a/ command to list all archived coupons. Alternatively, the find command explained below will search all archived coupons, thus displaying archives that match the supplied keywords below unarchived coupons. Finally, the expiring command will also include all archived coupons that are expiring in its results. Read the section on find and expiring respectively to find out more.

Format: archive INDEX

  • Archives the coupon at the specified INDEX.

Examples:

  • archive 1
    Archives the first coupon in the coupon stash.

Tip
 To keep your coupons more organized, Coupon Stash will automatically archive your coupons once their usage limit has been reached, or when they have expired.

4.8. Unarchiving a coupon: unarchive

Unarchive a coupon, thus bringing it back to your active coupons list.

Note
 To unarchive a coupon, you have to make sure that the archived coupon is visible in the coupon stash first. Read the section on the archive command to find out the ways that you can display archived coupons.

Format: unarchive INDEX

  • Unarchive the coupon at the specified INDEX.

Examples:

  • unarchive 1
    Unarchive the first coupon in the coupon stash.

4.9. Locating coupons by name: find

Find coupon(s) whose names contain any of the given keywords.

Format: find KEYWORD [MORE_KEYWORDS]…​

  • The search is case insensitive. e.g mALa will match Mala.

  • The order of the keywords does not matter. e.g. Rice Chicken will match Chicken Rice.

  • Only full words will be matched e.g. Chicken will not match Chickens.

  • Coupons matching at least one keyword will be returned (i.e. OR search). e.g. Chicken Rice will return Duck Rice, Chicken Chop.

Tip
 For easy finding of coupons, include the store or brand name in your coupon name!

Examples:

  • find ken
    For example, coupons with these names would be returned: Ken Kitchen, KEN RIDGE Optical, ken you build a snowman.

Note
 The find command searches the archive for matches too. Coupons that are found in the archive are displayed below the non-archived matches.

4.10. Listing all expiring coupons: expiring

Shows a list of all your coupons expiring on a date or during a MonthYear.

Format: expiring e/EXPIRY_DATE or expiring my/MONTH_YEAR

Examples:

  • expiring e/11-9-2020
    Shows you all the coupons that will expire on 11 September 2020.

  • expiring my/9-2020
    Shows you all the coupons that will expire during September 2020.

Note
 The expiring command will include archived coupons in its results too. Coupons that are expiring in the archives are displayed below the non-archived matches.

4.11. Sorting coupons: sort

Sorts the coupons in CouponStash in ascending order. It is possible to sort by coupon name or expiry date.

Note
 The sorting order will persist throughout the runtime of the program. The command will sort any coupons currently on screen, including archived coupons , if they are present on screen. Archived coupons will always appear below active coupons.

Format: sort PREFIX

  • The PREFIX can be either n/ or e/.

  • Using n/ would mean sorting by name, while e/ would mean sorting by expiry date.

Examples:

  • sort n/
    Sorts the coupon stash by name in ascending order.

  • sort e/
    Sorts the coupon stash by expiry date from earliest to latest.

4.12. Copying a coupon: copy

Copies a coupon as an add command to your clipboard so that you can easily share it with your friends/ family!

Format: copy INDEX

  • Copies the coupon at the specified INDEX.

  • The add command of the coupon will be copied to your clipboard. Simply Ctrl + V to paste it! (Cmd + V for macOS)

Note

  • Statistics like number of times used or amount of savings accumulated will not be copied.

  • The copied add command will only contain the following fields:

    • Name

    • Savings

    • Expiry Date

    • Limit

    • Promo Code (if any)

    • Condition (if any)

Examples:

  • list
    copy 2
    Copies the 2nd coupon in the coupon stash to an add command and copies it to your clipboard.

  • find chicken
    copy 1
    Copies the 1st coupon in the results of the find command to an add command and copies it to your clipboard.

4.13. Sharing a coupon: share

Shares a coupon as a .png image file. Now you can post your coupons on Instagram!

Format: share INDEX

Note
 Image generated looks exactly like how a coupon shows up in the user interface. Below is a sample of how a shared coupon image looks like:
example shared coupon

Examples:

  • list
    share 2
    Shares the 2nd coupon in the coupon stash and save it as a .png file.

  • find chicken
    share 1
    Shares the 1st coupon in the results of the find command and save it as a .png file.

4.14. Undoing the previous command: undo

Undo the most recent operation on the coupon stash. Only operations that change the coupons in the coupon stash can be undone.

Format: undo

Undo only works on the following commands: (i.e. commands that change the coupons in the coupon stash)

Note
 Changes to user preferences cannot be undone.

Examples:

  • edit 1 r/ 25-12-2020
    undo
    Undo the edit command. Remind date of 1st coupon reverts back to its original value.

  • delete 1
    undo
    Revert the delete that was performed. Deleted coupon is restored.

4.15. Redoing the undone command: redo

Redo the previously undone operation. This is akin to undoing an undo.

Format: redo

Examples:

  • edit 1 r/ 25-12-2020
    undo
    redo
    Un-undo the edit command. Remind date of 1st coupon is edited. value.

  • delete 1
    undo
    redo
    Un-undo the delete command. 1st coupon is deleted.

4.16. Displaying a Month-Year on the calendar: goto

Goes to the specified Month-Year on the calendar.
Format: goto my/MONTH_YEAR

Example:

  • goto my/12-2020
    Goes to December 2020 on the Calendar

4.17. Displaying a Coupon: expand

Displays a coupon in its own window, giving you a complete view of it.

Format: expand INDEX

  • Expands the coupon at the specified INDEX.

Examples:

  • expand 1
    Open the coupon at index 1 in a new window.

expand example
Example of an expanded coupon window.

4.18. Setting currency symbol: setcurrency

Sets the currency symbol used in Coupon Stash. This will force Coupon Stash to reload all coupons to use the new symbol instead.

  • The currency symbol may affect the visual look of the program, as well as modify commands entered!

Format: setcurrency ms/NEW_MONEY_SYMBOL

Examples:

  • setcurrency ms/€
    Sets the money symbol used in commands, as well as to display coupons' savings, to € (Euro). The changes will be visible immediately.

4.19. Viewing help: help

Open a browser window that accesses an offline copy of this user guide.

Format: help

4.20. Clearing all entries: clear

Clears all entries from the coupon stash.
Format: clear

4.21. Exiting the program: exit

Exits the program.
Format: exit

4.22. Reminding of coupon expiry

By default, all added coupons have a remind date that is 3 days before its stated expiry date. This default value can be changed during the process of adding a new coupon or by editing an existing coupon. The remind dates for all coupons are checked on program launch. All coupons that have a remind date which falls on the date of program launch will be listed in a popup window on launch. The popup window can be closed by pressing Ctrl + q.

ug reminder window
Popup window showing all coupons that have their remind dates set on the date of program launch.
Warning
 Remind dates are only checked during program launch. Thus, if a day passes while the program is open, even if there are coupons expiring on the new day, no new reminder window will open

As of now, there is no functionality for the disabling of reminders for coupons. This feature will be made available in version 2.0.

Examples:

  • add n/McDonald’s McGriddles p/ILOVEMCGRIDDLES e/31-12-2020 s/$2 sd/1-4-2020 l/2 t/value t/savoury

    Add a new Coupon without specifying a remind date. Note that the default remind date is 3 days before the state expiry date:
    ug mcdonalds mcgriddles

  • add n/Grabfood s/40% e/30-4-2020 p/GRAB40 t/delivery r/10-4-2020

    Add a new Coupon while specifying a remind date of 10-4-2020:
    ug Grabfood reminder

  • edit 1 r/10-4-2020

    Edit the coupon at index 1 and change its remind date to 10-4-2020.

4.23. Saving the data

Coupon data is saved in the hard disk automatically after any command that changes the data.

There is no need to save manually.

5. Keyboard Shortcuts

With Coupon Stash being optimized for efficient command line usage, how can we not include some nifty keyboard shortcuts to further streamline your workflow! This section introduces some of the keyboard shortcuts available for use in this program.

5.1. Restore previously entered command texts: ↑ and ↓

Pressing the ↑ keyboard button while the focus is on the command box allows you to restore the text of the previous executed command. Pressing the ↓ keyboard button allows you to revert to a more recently entered command.

Demonstration:

Up down arrow

5.2. Close expanded coupon or reminder windows: Ctrl+q

After expanding a coupon, you can close the expanded coupon window by keeping the focus on the coupon window and pressing the keyboard buttons Ctrl and q simultaneously. This shortcut also works for closing reminder windows.

Demonstration:

ctrl q

5.3. Cycle through tabs: Ctrl+Tab

You can press the keyboard buttons Ctrl and Tab simultaneously to switch tabs. Do note that the focus has to be on the main panel before the key presses would work.

Demonstration:

ctrl tab

6. FAQ

Q: How do I transfer my data to another computer?

A: Simply install Stash in the other computer and overwrite the empty data file with your intended data file.

Q: Can I add multiple coupons using a command line?

A: Sorry, not at the moment. We may consider adding this feature in version 2.0.0.

Q : Why do I need to tag my coupons?

A : Tagging is not compulsory. However, it allows you to group similar coupons together for easier execution. For example, you can easily delete all the coupons that are tagged, cheap. Do refer to section 4 for more detail.

Q : How do I store coupons with no ending date?

A : Sorry, at the moment, coupon entries with no ending date cannot be stored. You would need to enter a much further date like 1-1-2030. To be added in version 2.0.0

Q : How do you calculate the savings value?

A : Whenever a coupon is marked as done, Stash will automatically calculate the values saved based on the details of the coupon.

7. Command Summary

This section has a summary of all the commands.

Action Format

Add

add n/NAME e/EXPIRY_DATE s/SAVINGS [u/USAGE] [l/USAGE_LIMIT] [p/PROMO_CODE] [sd/START_DATE] [r/REMIND_DATE] [c/CONDITION] [s/SAVINGS]…​ [t/TAG]…​
e.g. add n/The Deck Chicken Rice s/20% sd/2-3-2020 e/30-8-2020 t/friend t/value

Edit

edit INDEX [n/name] [e/EXPIRY_DATE] [l/USAGE_LIMIT] [p/PROMO_CODE] [sd/START_DATE] [r/REMIND_DATE] [c/CONDITION] [s/SAVINGS]…​ [t/TAG]…​
e.g. edit 2 n/Chicken Up s/50%

Delete

delete INDEX
e.g. delete 3

List

list [PREFIX] e.g. list

Find

find KEYWORD [MORE_KEYWORDS]
e.g. find western chick

Sort

sort PREFIX
e.g. sort n/

Expiring

expiring e/EXPIRY_DATE or expiring my/MONTH_YEAR
e.g. expiring e/11-9-2020 or expiring my/9-2020

Used

used INDEX or used INDEX MONETARY_SYMBOL + ORIGINAL_AMOUNT
e.g. used 1 or used 1 $10

Saved

saved d/DATE_TO_TRACK_FROM
e.g. saved d/ 1-5-2020

Archive

archive INDEX
e.g. archive 1

Unarchive

unarchive INDEX
e.g. unarchive 1

Copy

copy INDEX
e.g. copy 1

Share

share INDEX
e.g. share 1

Undo

undo

Redo

redo

Goto

goto my/MONTH_YEAR
e.g.goto 9-2020

Expand

expand INDEX
e.g. expand 1

SetCurrency

setcurrency [ms/NEW_MONEY_SYMBOL]
e.g. setcurrency ms/€

Help

help

Clear

clear

Exit

exit

8. Appendix

8.1. Query expressions (coming in v2.0)

Query expressions serve to enable users to perform efficient batch operations on stored coupons using SQL-like syntax.

Examples:

  • edit favorites set tag=hated where expiry < 19-2-2020
    For all coupons tagged as favorites'', set their tag to hated'' if they expire before the 19th Feb 2020.

  • delete favorites where expiry < 19-2-2020
    For all coupons tagged as ``favorites'', delete them if they expire before the 19th Feb 2020.

8.1.1. Bulk edit

Format: edit tag set field1=value1, field2=value2, … [where condition]

  • The edit keyword is compulsory.

    • If selecting all tags, put tag as *.

  • The set keyword is compulsory.

    • If the field is present in a coupon, update the value, else create the field and value.

    • At least 1 field must be updated/added per edit operation.

  • The where keyword is optional.

    • The ==, >=, ⇐, >, <, !=, operators are supported in the condition.

    • Only default fields can be compared.

    • Condition syntax: DEFAULT_FIELD operator LITERAL_VALUE

    • AND/OR functionality is not available.

8.1.2. Bulk delete

Format: delete tag [where condition]

  • The delete keyword is compulsory.

    • If selecting all tags, put tag as *.

  • The where keyword is optional.

    • If the where keyword is omitted, deletes all coupons with that tag.

    • Follows syntax explained above.